3. Storage Client APIs
Even though the REST API and
the operations in the REST API are easily readable, the API doesn't
automatically create client stubs like the ones created by WDSL-based
web services. You have to create your own client API and stubs for REST
API operations. This makes the client programming more complex and
increases the barrier to entry for developers. To reduce this barrier
to entry, the Windows Azure SDK team has created two client helper
libraries: Microsoft.WindowsAzure.StorageClient from Windows Azure SDK,
and the Storage Client code sample. Both libraries are used to invoke
REST APIs of the Windows Azure Storage service. The
Microsoft.WindowsAzure.StorageClient library abstracts this by
providing a closed-source interface and therefore is less interesting
to developers who want to see the inner workings of the method calls.
In the Windows Azure CTP
version, a code sample named Storage Client became the choice of
developers for calling storage services because the
Microsoft.WindowsAzure.StorageClient wasn't available and also because
it was open source. It provided good insight into building your own
storage client library. The Storage Client made it easier to see the
end-to-end method calls to the Storage service. This chapter uses the
Storage Client code sample in sample applications and covers the class
structure and calling mechanisms in the
Microsoft.WindowsAzure.StorageClient namespace.
The following sections cover
the queue storage APIs from Microsoft.WindowsAzure.StorageClient and
the Storage Client code sample.
NOTE
You don't have to use
the Storage Client to make REST calls to the Storage service. You can
create your own client library for making REST operations to the
Storage service. In order to keep the book conceptual, I use the
Storage Client code sample helper library to interact with the Storage
service throughout this book. The source code for Storage Client is
available in the samples directory of the Windows Azure SDK or from the
Windows Azure code samples site, http://code.msdn.microsoft.com/windowsazuresamples.
3.1. Windows Azure Storage Client Queue API
The Microsoft.WindowsAzure.StorageClient namespace consists of classes representing the entire queue hierarchy. Figure 1 illustrates the core classes for programming Queue service applications.
As shown in Figure 1, four core classes are required for queue operations. Table 1 lists these classes and a short description of each of them.
|
The Windows Azure Storage
Client API is the recommended method for programming Storage service
applications. The API provides synchronous as well as asynchronous
methods for interacting with the Storage service REST API.
|
|
Table 1. Classes for the Queue Service
| Class Name | Description |
|---|
| CloudStorageAccount | A
helper class for retrieving account information from the configuration
file or creating an instance of the storage account object from account
parameters. |
| CloudQueueClient | A
wrapper class for getting references to the core queue objects. The
class consists of methods like GetQueueReference() and ListQueues(). |
| CloudQueue | Consists of queue operations like Create(), Delete(), AddMessage(), and GetMessage(). |
| CloudQueueMessage | Represents a queue message with properties like InsertionTime, ExpirationTime, NextVisibleTime, Id, and PopReceipt. |
In addition to
these core classes, classes like QueueAttributes and
QueueErrorCodeStrings represent more details about the queue.
The steps for programming simple queue applications with the queue classes listed in Table 1 are as follows:
Add the following using statement to your C# class:
using Microsoft.WindowsAzure.StorageClient;
Instantiate the CloudStorageAccount class from the configuration file:
CloudStorageAccount storageAccountInfo =
CloudStorageAccount.FromConfigurationSetting(configurationSettingName);
Or, instantiate the CloudStorageAccount class using account information:
CloudStorageAccount storageAccountInfo = new CloudStorageAccount(new
StorageCredentialsAccountAndKey(accountName, accountKey), new Uri
(blobEndpointURI), new
Uri(queueEndpointURI), new Uri(tableEndpointURI));
Create an instance of CloudQueueClient:
CloudQueueClient queueStorageType = storageAccountInfo. CreateCloudQueueClient ();
When you have an instance of the CloudQueueClient class, you can execute operations on the queue storage service as follows:
List queues:
IEnumerable<CloudQueue> queues = queueStorageType.ListQueues();
Create Queue
queueStorageType.GetQueueReference(queueName).Create();
Delete Queue
queueStorageType.GetQueueReference(queueName).Delete();
Add a message:
public void AddMessage(string queueName, CloudQueueMessage queueMessage)
{
queueStorageType.GetQueueReference(queueName).AddMessage(queueMessage);
}
Get messages:
queueStorageType.GetQueueReference(queueName).GetMessages
(numberofMessages, TimeSpan.FromSeconds(visibilityTimeoutInSecs));
Peek messages:
queueStorageType.GetQueueReference(queueName).PeekMessages(numberofMessages);
Delete a message:
public void DeleteMessage(string queueName, CloudQueueMessage queueMessage)
{
queueStorageType.GetQueueReference(queueName).DeleteMessage(queueMessage);
}
Set queue metadata:
public void SetQueueMetadata(string queueName, NameValueCollection queueProps)
{
CloudQueue queue = queueStorageType.GetQueueReference(queueName);
queue.Attributes.Metadata = queueProps;
queue.SetMetadata();
}
The call to SetMetadata() method calls the method on the queue service API in the cloud.
3.2. Storage Client Code Sample Queue API
The Storage Client project consists of five important classes in the context of the Queue service. Table 2 lists these classes and a short description of each of them.
Table 2. Storage Client classes for the Queue Service
| Class Name | Description |
|---|
| StorageAccountInfo | A helper class for retrieving account information from the configuration file. |
| QueueStorage | An
abstract class that has properties and methods at the account level of
the Queue service hierarchy. It has an AccountName property and the
method ListQueues(). |
| QueueStorageRest | A
class that extends the QueueStorage class and implements the abstract
methods. This class also has a nested class ListQueueResult,
representing the results returned by the Queue service. |
| MessageQueue | An
abstract class with signatures for the queue and message operations.
Some example method calls are CreateQueue(), PutMessage(), and
GetMessages(). |
| QueueRest | A class that extends the MessageQueue class and implements the abstract methods. |
Figure 2 illustrates the five classes listed in Table 2 and the relationships between them.
Following are some of the typical steps required to interact with the Queue service using Storage Client classes.
Add your account information in the <appSettings> section of your application configuration file (app.config or web.config):
<add key = "AccountName" value="[Your Account Name]"/>
<add key = "AccountSharedKey"
value="[Your Account Shared Key from the Developer Portal]"/>
To work with local
storage, add "devstoreaccount1" as the AccountName and
"Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=="
as the shared key.
Add the Queue service endpoint URI in the appSettings section of your application configuration file:
<add key="QueueStorageEndpoint" value="http://blob.core.windows.net"/>
To work with local storage, add the URI of the local Queue service resource, http://127.0.0.1:10001.
Create an instance of the StorageAccountInfo class from the configuration information you entered in the configuration file:
StorageAccountInfo account =
StorageAccountInfo.GetDefaultQueueStorageAccountFromConfiguration();
Create an instance of the QueueStorage class based on the account object:
QueueStorage queueStorage = QueueStorage.Create(account);
Call the ListQueues() method on the queueStorage object to get a list of all the queues in the account:
queueStorage.ListQueues();
To access a particular queue, call
MessageQueue messageQueue = queueStorage.GetQueue(queueName);
When you have a reference to the message queue object, then you can call not only queue methods like CreateQueue(), DeleteQueue(), and ListQueues(), but also message functions like PutMessage(), GetMessages(), and DeleteMessage().
